Date and Time methods
These methods are intended to format date and time using the Home Assistant native logic.
When you open Home Assistant and it is loading, it is possible that the user locale settings are not ready yet until the system finished to load all the resources. If you try to render a template using the sync methods to format dates and time at the beginning of this loading process, it is possible that the formatting wouldn't follow your language settings. This will be corrected if the template is reevaluated later, but to avoid any wrong formatting at the beginning, it is recommended to use the async methods instead, which will return a result when the locale settings are ready. If your template doesn't get rendered since the beginning, then the sync methods could be used.
The methods to format dates and time depend on the locale that the user has configured in Home Assistant, so the result of these methods is not deterministic. For the examples, a specific locale has been used.
formatDate and formatDateAsync
These methods format a date using the Home Assistant locale. They accept a date, a string ISO 8601 representation of a date or a number representing the timestamp in milliseconds.
// The result of all this examples will be "December 14, 2025"
// Using a date string
formatDate('2025-12-14');
// Using an ISO 8601 date string
formatDate('2025-12-14T00:00:00');
// Using a timestamp number
formatDate(1765715953817);
// Using a date
formatDate(new Date(2025, 11, 14));
// The result of all this examples will be Promises that will resolve to "December 14, 2025"
// Using a date string
formatDateAsync('2025-12-14').then((result) => { /* ... */ });
// Using an ISO 8601 date string
formatDateAsync('2025-12-14T00:00:00').then((result) => { /* ... */ });
// Using a timestamp number
formatDateAsync(1765715953817).then((result) => { /* ... */ });
// Using a date
formatDateAsync(new Date(2025, 11, 14)).then((result) => { /* ... */ });
formatDateTime and formatDateTimeAsync
These methods format a date with time using the Home Assistant locale. They accept a date, a string ISO 8601 representation of a date or a number representing the timestamp in milliseconds.
// The result of all this examples will be "December 14, 2025 at 12:00 AM"
// Using an ISO 8601 date string
formatDateTime('2025-12-14T00:00:00');
// Using a timestamp number
formatDateTime(1765666800000);
// Using a date
formatDateTime(new Date(2025, 11, 14, 0, 0, 0));
// The result of all this examples will be Promises that will resolve to "December 14, 2025 at 12:00 AM"
// Using an ISO 8601 date string
formatDateTimeAsync('2025-12-14T00:00:00').then((result) => { /* ... */ });
// Using a timestamp number
formatDateTimeAsync(1765666800000).then((result) => { /* ... */ });
// Using a date
formatDateTimeAsync(new Date(2025, 11, 14, 0, 0, 0)).then((result) => { /* ... */ });
formatTime and formatTimeAsync
These methods format a time using the Home Assistant locale. They accept a date, a string ISO 8601 representation of a date, a number representing the timestamp in milliseconds, or a string representation of a time in the format HH:MM or HH:MM:SS.
// The result of all this examples will be "12:00 AM"
// Using a time string
formatTime('00:00'); // It could also include seconds 00:00:00
// Using an ISO 8601 date string
formatTime('2025-12-14T00:00:00');
// Using a timestamp number
formatTime(1765666800000);
// Using a date
formatTime(new Date(2025, 11, 14, 0, 0, 0));
// The result of all this examples will be Promises that will resolve to "12:00 AM"
// Using a time string
formatTimeAsync('00:00').then((result) => { /* ... */ }); // It could also include seconds 00:00:00
// Using an ISO 8601 date string
formatTimeAsync('2025-12-14T00:00:00').then((result) => { /* ... */ });
// Using a timestamp number
formatTimeAsync(1765666800000).then((result) => { /* ... */ });
// Using a date
formatTimeAsync(new Date(2025, 11, 14, 0, 0, 0)).then((result) => { /* ... */ });
getRelativeTime and getRelativeTimeAsync
These methods get the relative time of a date using the Home Assistant locale. They accept a date, a string ISO 8601 representation of a date or a number representing the timestamp in milliseconds. These methods also accept a secondary optional boolean parameter to define if the result should be capitalized or not (by default it is false).
// The result of all this examples will be "in 2 weeks"
// Assuming that the current date is December 1st, 2025 at 12:00 AM
// Using an ISO 8601 date string
getRelativeTime('2025-12-14T00:00:00');
// Using a timestamp number
getRelativeTime(1765666800000);
// Using a date
getRelativeTime(new Date(2025, 11, 14, 0, 0, 0));
// The result of all this examples will be Promises that will resolve to "December 14, 2025"
// Assuming that the current date is December 1st, 2025 at 12:00 AM
// Using an ISO 8601 date string
getRelativeTimeAsync('2025-12-14T00:00:00').then((result) => { /* ... */ });
// Using a timestamp number
getRelativeTimeAsync(1765666800000).then((result) => { /* ... */ });
// Using a date
getRelativeTimeAsync(new Date(2025, 11, 14, 0, 0, 0)).then((result) => { /* ... */ });